The Very Best of Atari Inside/The Very Best of Atari Inside 1.iso/sharew/accs/cal_62a/cal62a.doc

Text File | 1992-03-25 | 87.9 KB | 1,861 lines

                         Cal v6.2: The Calendar Program
                        Copyright (c)1992 by Bill Aycock


Ever forgotten your anniversary or your kid's birthday? Missed a TV show
because you didn't remember what day it was on? Went to work an hour late (or
even worse, early!) when you forgot to reset your clock for Daylight Savings
Time? If this has happened to you, Cal may be able to help!

Cal is a calendar program with a difference - it lets you attach 'events' to
any day of the year by date, according to a day's position in the month, or on
a regular cycle. When Cal loads, it reads the current date from your system
clock and checks to see if any significant events are scheduled for the day. If
so, Cal displays an alert that shows you the day's events. (When Cal loads as
an ACC, it dings the system bell if a significant event is scheduled.) Cal can
also communicate with CodeHead's HotWire (v2.1 or newer) to set up the day's
alarms automatically!

Also included in this ARC file is Calshow, a program that reports on the
events you've stored in Cal and functions as an AUTO program, a full GEM-based
program, or a desk ACC. As an AUTO program, CalShow will read the events from
Cal and display upcoming events on screen, then pause so you can easily see
what's on tap for the next couple weeks. This should give you plenty of time to
plan for upcoming events!


====================================================

                    CONTENTS


       0. New Stuff in This Version

       1. Installation
         1.1. Installing from Scratch
         1.2. Converting from Older Versions
         1.3. DC-Squish Notes
         1.4. Limits

       2. Cal

         2.1. Concepts
           2.1.1. Event Types
           2.1.2. Importance

         2.2. Startup Actions
           2.2.1. Initialization and HotWire Alarms
           2.2.2. Alert Dialog
           2.2.3. Expired Event Dialog

         2.3. Main Calendar
           2.3.1. Types of Days
           2.3.2. Changing the Year or Month
           2.3.3. Looking at a Specific Day
           2.3.4. General Information
           2.3.5. Other Buttons

         2.4. Extras Dialog
           2.4.1. Days Between Two Dates
           2.4.2. Date of Easter

         2.5. Preferences Dialog
           2.5.1. Desk Menu Entry
           2.5.2. When An Event Expires
           2.5.3. Other Settings

         2.6. File Dialog
           2.6.1. Cal File Types
           2.6.2. Loading
           2.6.3. Saving
           2.6.4. Merging
           2.6.5. Talking with Other Cals
           2.6.6. Mass Erase Dialog
           2.6.7. Setting HotWire Alarms
           2.6.8. Checking Expired Events

         2.7. Scan Dialog
           2.7.1. Concepts
           2.7.2. How Scanning Works
           2.7.3. Scan Display
           2.7.4. Finding Events
           2.7.5. Scan Options

         2.8. Find Dialog
           2.8.1. Search String
           2.8.2. Type, Status, Importance Filters

         2.9. Edit Dialog
           2.9.1. Edit Mode
           2.9.2. Fields on the Edit Screen
           2.9.3. Looking at Events
           2.9.4. The When Dialog
           2.9.5. Changing Existing Events
           2.9.6. Adding New Events
           2.9.7. Erasing Events

       3. Calshow
         3.1. Running from the AUTO Folder
         3.2. Running as a PRG or ACC
           3.2.1. Calshow Prefs
           3.2.2. This Run Only

       4. Final Notes, Version History

       5. Keyboard Shortcuts
         5.1. Main Calendar
         5.2. Alert Dialog
         5.3. Edit Dialog
         5.4. Expired Event Dialog
         5.5. Extras Dialog
         5.6. File Dialog
         5.7. Find Dialog
         5.8. Mass Erase Dialog
         5.9. Preferences Dialog
         5.10. Scan Dialog
         5.11. When Dialog
         5.12. Calshow Dialog


====================================================


0. New Stuff in This Version


New in Version 6.2:

A number of changes to both Cal and Calshow give you more information and
should make the programs more useful as scheduling aids. Highlights:

Calshow:

>> The alarm time for each event is now listed on all displays. In addition,
the events for each day are sorted by alarm time and importance, so a day's
events are listed in the order in which they occur. Events that have an alarm
time attached are shown preceding events with no alarm time. This means the
alarm time field is useful even if you don't have HotWire!

>> The Calshow dialog now offers two new quick-view buttons, "Week" and
"Today". These buttons let you instantly see all events scheduled on the
current date, or on the current date plus the next week. Unlike Calshow's
normal mode, the advance notice for your events is ignored so you get a full
list of all upcoming events in the chosen time span.

>> Instead of exiting after Calshow completes a display, you now return to
the Calshow dialog. This makes it easy to flip between the Today and Week
quick-views, the normal Coming Events list, and displays of a specific time
span.

>> The Help key now makes Calshow wait for any keypress before continuing,
instead of merely resetting the wait time. If you have a full screen of
events to look at, you won't need to keep hitting the Help key!

Cal:

>> The Cal dialog can now be moved around the screen. The dialog's relative
position is saved whenever you save your Cal setup. If you wish, you can have
Cal use this saved location whenever it runs. (This will be most useful for
those with large-screen monitors.)

>> The beginning of each event in the Alert Dialog is now marked with a
small symbol, making it easier to tell where one event ends and the next
begins. The symbol is a triangle for a normal event, or a clock face for an
event that has an alarm attached. If you click on a clock face, the alarm time
for that event is displayed in the box at the top of the dialog.

>> The Scan Dialog now shows more information. The title bar shows you how
many events are currently selected and the total number of events you've
defined. The alarm time is displayed on the small schedule line above each
event, and if the event is a one-time date event occurring in a single month,
the day of the week is also displayed.

>> The Scan Dialog also includes a small bullet next to each event; if you
click on the bullet, the event is 'hidden' (deselected). This allows you to
select any arbitrary group of events. Once you have a group selected, some
additional options are available by clicking the title bar - you may either
erase all the selected events, or swap the 'selected' status of all events.
This feature should make it easier to manage a large collection of events.

>> The Extras Dialog now offers another type of date calculation. In
addition to finding the date of Easter or the number of days between two
dates, you may add or subtract any number of days from a base date and find
the resulting date.

>> The Edit Dialog shows you more information for any cyclic event. The small
text field that shows how many days it will be to the next occurrence now
also displays the date of the next occurrence.

>> There is also a new "Show When" button on the cyclic event edit screen.
Clicking this button will bring up a new When Dialog that lists the date and
day of the week of every occurrence of the event. If you click on a date, you
will return to the calendar screen with that date's month displayed.


====================================================


1. Installation


1.1. Installing from Scratch

Installing Cal and CalShow is simple. Cal comes ready to go, pre-configured
with over a hundred commonplace and obscure events. To use Cal, either install
it as a desk accessory in the normal fashion, or just run it as a program. Cal
uses well under 90K of memory, and runs on any ST or TT in any resolution.

Likewise, CalShow can run as a normal GEM program from the desktop or as a
desk accessory. However, CalShow can also run from the AUTO folder, so you can
be reminded of upcoming events every time you boot your system. To do so,
create a folder named AUTO on your boot disk and copy CSHOW62.PRG into it. Like
Cal, CalShow can run in any resolution on any ST or TT. It uses under 50K as an
accessory.

NOTE: You can also place Cal in your AUTO folder if you want. It won't _do_
much of anything when you boot up, but it won't crash your system! <grin>


1.2. Converting from Older Versions

In the past, upgrading to a new version of Cal meant either running your old
version and saving your events in the new one, or running a separate conversion
program (in the case of moving from 4.x to 5.x). It's even easier now!

Even though Cal's database format has changed again, Cal 6 lets you load
events _directly_ from a version 5.x Cal file. Simply run Cal 6, click the File
button, click the Load button, and use the item selector to find your old copy
of Cal. Cal 6 will read in all your events and convert them to the new format
automatically. In the process, HotWire alarm information is removed from your
messages and stored in the new alarm settings fields, and the importance of
each event is set to level 7 for significant events, level 4 for normal events,
and level 1 for trivial events.

When you return to the File dialog, click Save to store your new events into
the Cal 6 program file. Simple!


1.3. DC-Squish Notes

Cal and Calshow are compatible with DC-Squish 1.4, Double Click's program
compressor. This little jewel basically lets you "arc" your programs and desk
ACCs to save space on your disk. The program is automatically unArced when you
run it (or load the ACC). Another advantage of DC-Squish is that since the
program files are smaller, they generally load a bit quicker (especially from a
floppy). DC-Squish is a part of the DC Utilities package available wherever you
buy ST software.

To squish Cal and Calshow, simply follow the DC-Squish instructions. When you
click the "Squish" button, you should see an alert that says "offset protocol
recognized- use it?".

            IMPORTANT: YOU MUST ANSWER YES TO THIS QUESTION!!!

This makes DC-Squish compress the program part of Cal and Calshow, but leave
the embedded data alone. If you answer No instead, you will not be able to save
your events in Cal, and Calshow won't be able to read Cal's event data! (If
your copy of DC-Squish doesn't support the 'offset protocol', DO NOT use it on
Cal or Calshow- upgrade to the latest version of the DC Utilities!)


1.4. Limits

Cal 6 provides around 20K of space for the event database, and enough room to
hold 511 events in its index. There are no limitations for any group of events
(e.g., events on a single day, events to be scanned) other than those imposed
by the size of the database and index.

If each of your events uses every character on all three lines available for
the message, Cal will run out of room at around 166 events. If you define the
maximum number of events, then each event can have a message 17 characters in
length. In practice, most users will fall somewhere between these two limits.


====================================================


2. Cal


2.1. Concepts

Cal is, among other things, a universal calendar. You can use Cal to see the
calendar of any month in any year from the year 1 to the year 9999. But more
than that, Cal is designed to help you remember birthdays, anniversaries, TV
shows, and more- any event that occurs on a particular day. It works equally
well for weekly TV shows, monthly meetings, birthdays that only roll around
once a year, or once-in-a-lifetime experiences. This section explains some
basic concepts that will help you make the most of Cal and Calshow.


2.1.1. Event Types

The concept of an "event" is central to Cal. Webster defines an event as
"that which comes, arrives, or happens, especially an incident of importance".
In Cal, an event is any incident that occurs on one day. Cal recognizes four
basic types of events: recurring date events, one-time date events, positional
events, and cyclic events.

A "date event" is any event that occurs on a specific date in a month.
Birthdays and anniversaries are date events; some holidays, such as New Years
and Christmas, are date events. Bills that are due on the 15th of the month are
date events.

The above examples are "recurring" date events, since they occur more than
once. Birthdays and holidays happen every year, bills are due every month. The
other type of date event is a "one-time" event. If you have a dentist
appointment on September 21st, 1991, you can set it up as a one-time event. The
difference between one-time and recurring date events is that recurring events
happen over and over, while one-time events occur in one specific year; after
the event has passed, it's no longer valid- it "expires".

The third type of event is the "positional event". You schedule a positional
event by its position in the month. Examples: Thanksgiving Day is always the
fourth Thursday in November; the last Sunday in October is the end of Daylight
Savings Time. Ptaug, our local Atari users group, holds meetings on the last
Wednesday of every month except July and December.

Cal 6 provides a fourth event type, the "cyclic event". Cyclic events are
those which occur repeatedly over a fixed time span, every so many days. If you
get paid every two weeks, add a cyclic event for every 14 days to remind you.
If you need to mark your summer vacation so you won't schedule a meeting during
that time, you can set up a cyclic event that occurs every day during that
time. Cal allows cyclic events to occur every one to 255 days over a period
of up to 100 years. Just tell Cal the date of a cyclic event's first
occurrence, how often it occurs, and an ending date after which the event
expires.


2.1.2. Importance

Another basic concept is that of an event's "importance". Starting with Cal
6.0, an event can have an importance level of zero to nine, with zero as the
least important and nine as the most. The importance level affects the way Cal
displays an event, and gives you another way to select groups of events as
you'll see later.



2.2. Startup Actions

Several important things happen when you start Cal. If you run Cal as a
program, these actions occur all at once; if you load Cal as an accessory
instead, some things happen when the accessory loads and others don't occur
until you select the accessory from the Desk menu.


2.2.1. Initialization and HotWire Alarms

Cal starts out by checking if it's running from the AUTO folder. Any program
that relies on GEM cannot run while your ST is just booting up. Most GEM
programs don't check to see if they're running at boot time, and simply crash
your system... Cal DOES check, and DOESN'T crash- it just displays a short
message on your screen and gracefully quits.

Next, Cal reads your system clock to find out what day it is. Then it checks
to see if any events are scheduled for the current day. If an event is
scheduled, two things happen. First, Cal checks to see if CodeHead's HotWire is
active. (HotWire is an enhanced desktop replacement- very powerful, easy to
use... highly recommended!) If it is, Cal can set up to sixteen HotWire alarms
for you, to keep you on track during the day! (Note: Cal is smart enough to
skip setting alarms for times that have already passed. Also, Cal won't set
alarms that already exist, so you don't need to worry about having a dozen
copies of the same alarm go off at once. :-) HotWire must be at version 2.1 or
above for this feature to be active.

Then, if Cal is loading as an accessory, it will ding the system bell to
remind you that something is happening today.


NOTE: Cal will set your alarms as soon as he initializes. Also, every time
you go to the main calendar screen Cal will check to see if today's date has
changed. If so, Cal will automatically set your alarms for the new day. You
can also ask Cal to set the day's alarms at any time from the File dialog;
more on that later.

ANOTHER NOTE: If you own CodeHead's MultiDesk Deluxe and you set up Cal as a
non-resident accessory, you MUST include the "-I" parameter in your TITLES.MDX
file if you want to set HotWire alarms when you boot! This parameter tells
MultiDesk to let Cal perform its initialization - which includes setting the
day's alarms - when you boot up your system. Cal will still work fine as a
non-resident ACC without the -I parameter, but your alarms won't be set until
you actually choose Cal from the MultiDesk menu. For further information, see
Appendix A in the MultiDesk Deluxe user guide.



Next there's a break in the action. If Cal is running as an accessory,
nothing else happens right now- the rest of the initialization waits until the
first time you select Cal from the Desk menu. If you're running Cal as a
program, there's no pause; it keeps right on truckin' along.


2.2.2. Alert Dialog

The next step of Cal's initialization is to let you know about any events
scheduled for the day. If nothing is on tap, this step is skipped; otherwise,
Cal brings up the Alert Dialog.

The title bar at the top of this dialog will normally read "Events of the
Day". However, if Cal tried setting any HotWire alarms for you, the title bar
will tell you so. It will also let you know if Cal was unable to set one or
more of your alarms; be sure to read the message to find out the status of the
day's HotWire alarms.

NOTE: If the MOST important event on a given day has an importance level of
zero, the Alert Dialog will NOT be displayed automatically. The only time this
is not the case is when the level-zero event is an alarm, HotWire is active,
and Cal was unable to set the alarm for you. If this happens, Cal will display
the alert so you can see the error message.

The upper box of this dialog shows the day of the week, date, and year, plus
the Julian date (that's the day of the year, folks) and how many days remain in
the year. The main part of the dialog is a large box that lists the events
scheduled for the day.

This box can show up to eight events at a time, depending on how many lines
of text each event contains. If all of the messages for the day fit on this
screen, the "next page" button at the bottom of the screen will be grayed out;
if there are too many messages to display at once, you can click this button to
view the rest of the events. Each click shows you the next few events; after
the last waiting event is displayed, Cal 'wraps around' to the first one and
starts over. Unlike older versions, there is _no limit_ to the number of events
Cal can display on a single day (other than the total number of events defined,
that is)... but if you end up with more than 50, I'd _still_ recommend hiring a
secretary. :-)

The first line of each event is marked with a small symbol, either a triangle
(for a normal event) or a clock face if the event has an associated alarm. This
makes it easy to see where one event ends and the next begins. In addition, you
may click on a clock face; this will display the event's alarm time in the box
at the top of the dialog.

You may edit an event from this screen if you wish; click on the message text
or on an unused slot in the display (or press a number key on the numeric
keypad). This takes you to the Edit Dialog; more on that later. Since we're
still booting up, click the Cancel button or just hit Return and Cal will
finish its initialization.


2.2.3. Expired-event Dialog

As the last step of its initialization, Cal searches your events looking for
one-time date events and cyclic events. If any are found, Cal looks to see if
each event's last occurrence has passed; if so, then the event has expired.

One of three things happens next. First, Cal can ignore the fact that the
event has expired, and just continue initializing. Second, Cal can go ahead and
erase the old event for you automatically. Third, Cal can ask you what to do
with the event. Which of these happens depends on how you've set up Cal; the
initial setting is for Cal to ask you what to do, but you can change this to
your taste. (See the Preferences section for information on how to do this.)

Cal asks you what to do with an expired event by displaying the Expired Event
Dialog. The top of this dialog shows the event and the day it was scheduled to
occur. The buttons on this dialog will let you erase the event, leave it alone
for the moment, or convert a one-time date event to a recurring event.

If you prefer to wait until later to look through the expired events, press
the UNDO key to cancel the process. When you have more time, you can start the
process again from the File menu.



2.3. Main Calendar

Most of Cal's main screen is taken up by a calendar display. The month and
year of the calendar is shown right underneath the display, and there is a
column of month buttons to the right. There are plenty of other buttons too; in
fact, almost anything you click on will do something <grin>. More about that in
just a minute...


2.3.1. Types of Days

The calendar display has changed significantly from older versions. If Cal is
showing the current month and year, then today's date will be highlighted
(white numbers on a black background). Days in the preceding and following
months are grayed out. The other days in the month may be surrounded by boxes
of varying thickness. These borders indicate the importance level of the _most
important_ event falling on that date... a heavy border means an important
event (levels 7 to 9) occurs that day, a medium border means the most important
event is between four and six, and a skinny border means that a level 1 to 3
event occurs. If there is no border surrounding a day, then only level zero
events occur then (or, of course, nothing at all is scheduled that day).


2.3.2. Changing the Year or Month

There are a couple ways to look at different months and years. First notice
the column of buttons to the right of the calendar. These buttons are labeled
with the names of the months; click one of these buttons to move directly to
that month. The bottom two buttons are labeled Next and Prev, and will skip
forward or back one month. (Also note that the buttons are marked like the top
row of keys on your keyboard, with numbers 1 to 0 plus - and =... pressing one
of these keys will act just like clicking the appropriate month button. You may
also use the numeric keypad keys 1-9, (, ), and / to select a month. The left
and right arrow keys move you forward or back a month like the Next and Prev
buttons.)

Next, note the arrow and double-arrow buttons right underneath the calendar.
These buttons, or the up and down arrow keys, move the display forward or back
one or ten years at a time.

If you want to look at a specific year, click on the box that shows the
current month and year. When you do this, you see a dialog that allows you to
type in the year you want. You'll probably find this easier than clicking the
up and down buttons.


2.3.3. Looking at a Specific Day

To find out more about a specific day or discover the reason for a border
around a number, simply click directly on that day in the calendar. This takes
you to the Alert Dialog which we (I :-) talked about earlier. You'll see the
date spelled out and a list of the day's events.

(Incidentally, this is the easiest way to add a new event to Cal -- look at
the month the event falls in, and click on the day. When the Alert Dialog shows
up, click on the text of any message or on an empty message slot. You'll go to
the Edit Dialog, with the date preselected, ready to add a new event. We'll
discuss that part later; right now, let's finish up with the main screen.)


2.3.4. Other Buttons

The buttons across the bottom of the main calendar screen will take you to
several other dialogs, which are explained in detail below.

The question-mark button takes you to the Extras dialog, where you can find
the date of Easter or perform date calculations.

Today, obviously enough, tells Cal you want to see the calendar of the
current month. If you already looking at the current month, then Cal will show
you the Alert for today's date.

The Prefs button allows you to customize Cal's behaviour from the Preferences
dialog.

The File button lets you load or save Cal's events, erase an entire month's
worth of events at once, or check Cal's database for events which have
expired.

The Scan button moves you to the Scan Dialog, where you can see a number of
events at once.

The Quit button lets you exit Cal.

NOTE: Cal keeps track of whether you change any of your events or customize
Cal's setup. If you look right under the column of month buttons, you'll see
the word SAVED or CHANGED to remind you.

If you've changed something during your Cal session but haven't saved your
changes, you get a chance to do so when you click Quit. An alert appears that
asks you if you want to save the new information, resume what you were doing in
Cal, or go ahead and quit. Choose the one you feel is most appropriate. If you
select Save, the GEM item selector will appear so you can locate the Cal file.
(If you press the Alt key when you select Save, you'll go to the File dialog so
you can save to a file or to a Cal ACC.) After you save your events to a file
successfully, you'll exit Cal; otherwise you'll return to the main dialog.

WARNING: If you run Cal as a program (or a non-resident ACC) and decide to
exit without saving your changes, they're GONE. If you're running Cal as a
regular accessory, your changes will still be in place when you next open the
ACC (and, if you _still_ don't save your setup, you'll be reminded when you try
to exit again).

ANOTHER NOTE: One of your options is to have Cal erase expired events for you
automatically. When this happens, the event is removed from the copy of Cal
currently in your Atari's memory. This means Cal's setup can change _even if
you don't do anything_! If you see the "setup has changed" alert when you exit
Cal but you haven't changed anything, it's probably because Cal has erased an
expired event for you.


The last button on the main screen is the largest one- it's the main title
bar that normally reads "Calendar 6.2". When you click on the title bar, you go
to a special screen that shows you the current version number and release date,
how many of each event type is currently defined, and where to send your
shareware donation <grin>. Press any key or click the mouse button to exit this
screen.

The title bar also allows you to reposition Cal's dialog on the screen. Click
on the title bar and hold down the mouse button, then drag the outline of the
dialog to the desired location and release the button. The relative position
of the dialog is saved whenever you save your setup; if you wish, you can tell
Cal to use this saved position automatically when it starts up.



2.4. Extras Dialog

The Extras dialog is a simple screen that lets you find the number of days
between two dates or the date of Easter for a given year, or lets you add or
subtract some number of days from a base date and find the resulting date.

Use the top half of the dialog to perform date calculations. Enter a base
date at the top, then type in a date (to find the days between) or a number of
days (to calculate a new date), then press Enter. The two radio buttons let you
choose USA (month/day/year) or European (day/month/year) style dates.

If you leave part of a field empty, Cal will use the current date (month,
day, or year) for that value. If you leave both empty, Cal will gladly tell you
that there are zero days between today and today. :-)

The bottom half of the dialog will calculate the date of Easter for a given
year. (Betcha didn't know you could calculate that, did ya? :-) Type in a year
and hit Enter, and Cal will tell you when Easter falls that year.

Click Exit or press Undo to leave the Extras dialog.



2.5. Preferences Dialog

As was mentioned above, you can customize several aspects of Cal's behaviour.
These include the handling of expired events, whether to use USA or European
dates, and a number of other options. To change any of these items, click  the
Prefs button on Cal's main calendar screen.

2.5.1. Desk Menu Entry

The top of this dialog contains a text field labelled "Desk Accessory Menu
Entry". When you run a fresh copy of Cal as a desk accessory, it shows up in
the menu as "Calendar 6.2". If you wish, you can change this entry by typing in
a new entry to use. If you have a large number of events to keep track of, you
may want to split them up between two or more copies of Cal... this feature
gives you a way to distinguish between the different copies in the Desk menu.
(The string you type in here also shows up in the main screen's title bar, so
you can tell which copy of Cal you're running.)

NOTE: When Cal runs as a non-resident ACC under MultiDesk Deluxe, the entry
in MultiDesk's menu comes from a special list you set up in your TITLES.MDX
file. That means if you change the title here, it WON'T automatically change.
See your MultiDesk Deluxe guide for more information.


2.5.2. When An Event Expires

Underneath the menu entry field are a number of radio buttons. The lower left
group lets you tell Cal how to handle an expired event. There are three buttons
in this group: Erase the event, Leave it alone, and Ask what to do. If you
select Leave It, then Cal will never check for expired events unless you choose
to do so from the File dialog. If you select Ask, then Cal will ask you what to
do with each expired event when you first run Cal. You can also select Erase
It- when you do, Cal will automatically erase any event that has expired.

NOTE: You must save your Cal setup to disk after an expired event has been
erased; otherwise it will still be in Cal's database on disk, and will be there
the next time you load Cal. Also, Cal keeps track of any changes that were made
in a session. When you exit Cal, it checks to see if you've saved your changes-
if not, you'll see an alert asking if you want to save your changes. Remember
that if _Cal_ erases an expired event for you, you may see this alert even
though _you_ haven't changed anything!


2.5.3. Other Settings

Between the menu entry and expiration setting is a box labeled "Default
Values". When you add an event, you can assign a particular number of days of
advance notice for the event; Calshow pays attention to this number when it
builds its display. The first field in the Default Values box is marked
"days:", and tells Cal what value to use as the default notice whenever the
Edit dialog shows you an empty template. The second field is marked "level:",
and allows you to set the default importance level for new events.

The right side of the Prefs dialog has a box labeled Options which control a
number of features. In each case, select the button next to a feature you want
to turn on or deselect the button to turn the feature off:

The 'Alarms' button gives Cal permission to set HotWire alarms. IF THIS
BUTTON IS NOT SELECTED, CAL WILL NEVER SET ANY HOTWIRE ALARMS ON ITS OWN! The
only way to set alarms when this button is not selected is to choose the Set
Alarms option from the File dialog.

The button marked 'Beeps On' asks Cal to ding the ST's bell whenever a GEM
alert is displayed. You shouldn't see many alerts normally, but feel free to
turn off the beeps if you wish.

When the 'Euro Date' button is selected, the European day/month/year style is
used for all dates instead of the USA style month/day/year. (Actually, in most
cases Cal will display the month name spelled out, or the first three letters
of the name. Or, to show a number of months at once, Cal displays a string with
the first letter of each month name, or a period if the month isn't selected.
Example: "JF........ND" indicates January, February, November, and December.)

You may select the button marked '24hr Time' if you would prefer to see alarm
times in military 24-hour time instead of 12-hour AM/PM time. This setting
affects the display in the Scan dialog and the Alert dialog.

The 'Zoomboxes' button asks Cal to draw decorative shrinking boxes when
changing from one dialog to another. Unless you have a fast machine and a
blitter, you'll probably want to leave this button deselected. :-)

If the 'Location' button is selected, Cal will use the saved position of the
dialog when it appears. Otherwise, the dialog will be centered on screen. (The
location is saved as a relative position, so you never need to worry about
Cal's dialog appearing halfway off the screen!)

The last section of buttons in the Prefs dialog lets you decide if you want
to be warned before you add, replace, or erase an event. Some people find these
alerts irritating, intrusive, or excessive, so I've supplied a way to turn them
off. Simply deselect the button, and be sure to save your changes. (Note: in
older versions, the alerts occurred after the fact. That was like locking the
barn door after the horse escaped, and I asked myself many times why I did that
<g>. They work correctly now, and ask you BEFORE the event so you get a chance
to change your mind.)


After you make any changes in the Preferences dialog, be sure to save the new
information in the Cal program file! Either save the information from the File
dialog, or you'll have a chance to do so when you exit Cal.



2.6. File Dialog

The File Dialog allows you to save the events and preferences you've stored
in Cal. There are also options to reload a new set of events into Cal, merge
the events from a Cal file into Cal without erasing what's already there, erase
a number of events at once, check to see if any of your events have expired, or
set HotWire alarms for the day.

There are several important concepts to keep in mind here:

   1. BEFORE you run Cal or load it as a resident desk accessory, all
      your events and preferences are stored IN THE CAL PROGRAM FILE.

   2. AFTER you start Cal or load it as a resident desk accessory, your
      events and preferences are stored IN YOUR COMPUTER'S MEMORY.

   3. Once Cal is running, CAL HAS NO CONNECTION WITH THE ACTUAL PROGRAM
      FILE ON DISK.

   4. This means that any changes you make in Cal - adding new events,
      changing existing events, or setting new preferences - ONLY AFFECT
      THE COPY OF CAL IN YOUR ST'S MEMORY! If you want to make your
      changes permanent, you must SAVE your setup to the program file.

   5. This also means that once Cal is running as a standard accessory,
      CHANGES YOU MAKE TO THE PROGRAM FILE DO NOT AFFECT THE CAL ACC!
      If Cal is running as an ACC, and you run Cal separately as a program,
      the changes you make to the PROGRAM will NOT show up in the ACC
      until you load the new setup from disk (or save it to the ACC).


2.6.1. Cal File Types

There are two basic types of Cal files. The first is the Cal program file
itself. Your events are stored in the actual program file until Cal starts up.
(Note: the format of Cal 6's database is not identical to older versions. Cal 6
will let you load your events from an older 5.x version, but you will not be
able to save to an old version.)

The second type of Cal file is an external Cal data file. Starting with
version 6.0 of Cal, you can save your _events only_ to a separate file for
archiving, transporting, or other special uses. A Cal data file is around 20K
in size and contains only the event database; no preferences or program code.

Note: Versions 4.9 and up of the Whatis File Identifier can recognize Cal
data files. The latest versions of Whatis and Cal can always be found on
Compuserve's Atari Productivity Forum (GO ATARIPRO at any ! prompt).


2.6.2. Loading

The Load From File button in the File dialog lets you completely replace
Cal's events with those stored in a disk file. Click the Load button, use the
item selector to choose a file from which to load, and click OK. If the
operation was successful, Cal will contain the same events that are present in
the disk file.

You can load events from either the Cal program file or from an external Cal
data file. When you load from the program file, your preferences are loaded at
the same time. If you load from a Cal data file instead, only your events are
changed (since the data file doesn't contain any preference data).

Cal 6 will also let you load your events (but not preferences) from a copy of
Cal version 5. As the events are loaded, they are converted to the new Cal 6
format automatically. This makes it simple to convert to Cal 6 from an older
version of Cal.


2.6.3. Saving

The Save To File button allows you to save your events to a disk file. To
save all your events and preference settings to the Cal program file, click
Save, use the item selector to locate Cal, then click OK. If the operation was
successful, your copy of Cal on disk will contain the same information as the
copy of Cal that is currently running.

You also have the option of creating a separate Cal data file, or saving your
events to an existing Cal data file. To create a new file, simply type a new
filename when the item selector appears. You'll be told that the file doesn't
exist, and asked if you wish to create a new file; click Yes or hit Return, and
Cal will save all your events into a new data file.

It's even easier to save your events to an existing Cal data file - just
select the data file with the item selector, as if it were the Cal program
file. Cal can tell which type of file you've selected, and will save in the
correct format automatically.

Reminder: Cal 6 cannot save events to an older version of Cal. If you see an
alert that says "Not Cal, or wrong version", try again and be sure you select
your version 6 file.


2.6.4. Merging

Cal 6 adds the ability to 'merge' events from any version 6 Cal program or
data file into its database. When you merge events, none of the events
currently in Cal are changed - Cal reads the events from the file one by one,
and if they are not already present, they are added to what's already there.
Exact duplicates are ignored, so you won't need to worry about having two
copies of each event.

Events cannot be merged from an older version of Cal. To accomplish this,
first save the events you've defined in Cal to an external data file, then load
the events from your older version. When that's complete, you can merge the
events from the data file you created.


2.6.5. Talking with Other Cals

Versions 6.1 and later of Cal have the ability to communicate with any Cal
ACCs in your system. If you have Cal installed as an accessory and then run Cal
as a program, the program will be able to read the events from or save a new
set of events into the accessory. If you have two or more copies of Cal running
as ACCs, each will be able to read or write the events stored in the other.
This communication is controlled by three buttons and an editable text field in
the File Dialog.

The two buttons on the right of the dialog, under the Save to File button,
are labelled 'load from acc' and 'save to acc'. When these buttons are enabled,
you can use them to read or write events from an active Cal ACC just as you
would from a Cal program file.

To the left is a button marked 'rescan for acc', and underneath this button
is a box marked 'name' with a text entry field. These two objects control which
copy of Cal you are talking to.

When your ST loads an accessory, GEM keeps track of the file name. Later,
applications can ask GEM if a particular ACC has been loaded. To talk with one
particular Cal ACC, type the filename of that ACC, minus the extender, into the
Name field, then click the Rescan button. Cal will ask GEM if that file has
been loaded; if so, the load-from and save-to buttons will be enabled.

NOTE: When Cal tries to load from or save to an ACC, it will wait up to five
seconds for the ACC to respond. Normally the process will be very quick, but if
you have Cal set up as a non-resident MultiDesk MDX, it will take MultiDesk a
couple seconds to load Cal.

IMPORTANT NOTE: You WILL NOT be able to save your events successfully into a
non-resident copy of Cal! The process may appear to finish without error, but
once the Cal MDX has responded, MultiDesk unloads it from memory- meaning that
none of the new events are saved. There is currently no way to prevent you from
trying this, but future updates to MultiDesk Deluxe will make it possible. Cal
is already set up to take advantage of this feature when it is available.

ANOTHER NOTE: The restrictions dealing with MultiDesk ACCs that talk with
other ACCs applies to Cal. See your MultiDesk manual for more information.


2.6.6. Mass Erase Dialog

This dialog is used to erase all the events in one or more months at one
time. Click the File dialog's Erase button and the dialog will appear; then
select the months you wish to erase and click the Erase button. If you respond
Yes to the alert that appears, all the events that occur in the selected months
will be removed. Cyclic events are not affected.

NOTE: This process entails moving around a lot of data, so it may take awhile
to finish, depending on how many events you have and which months are being
erased. The cursor will change to the busy-bee shape while Cal is working. Be
sure to give Cal enough time to complete the process!

You also have the option of erasing ALL OF YOUR EVENTS AT ONCE. If you select
the All button, then verify that you really want to do so, Cal will erase every
one of the events you've defined. This process takes only a fraction of a
second. When it completes, you will have a totally empty copy of Cal with no
events defined at all.


2.6.7. Setting HotWire Alarms

The lower left button on the File Dialog is marked 'set Alarms'. When you
click this button, Cal will check every event scheduled for the current date
and set any HotWire alarms that aren't already set. You'll see an alert that
tells you how many alarms were attempted and how many were set. This button
will be grayed out if HotWire 2.1 or later is not active in your system. (Note:
since Cal is very good about setting alarms when needed, you'll only need to
use this feature after you've defined a new alarm for the current day. In most
other cases, the report will show that no new alarms were set.)

NOTE: If you select this option, Cal will set the appropriate HotWire alarms
even if you've turned off alarms in the Preferences dialog.


2.6.8. Checking Expired Events

The last option in the File Dialog allows you to check all your events and
find those which have expired. For each expired event, you will see the Expired
Event Alert. You may leave an expired event alone for the time being, erase the
event, or convert the event from a one-time date event to a recurring date
event. See the section above on the Expired Event Dialog for more information.



2.7. Scan Dialog

The Scan Dialog lets you view a number of events at once. You can browse
through a summary of all your events, or use the Find dialog to select a subset
of events to view.


2.7.1. Concepts

Cal keeps an index of all the events you've set up. This index is sorted by
month, date (for a date event) or week and weekday (for a positional event),
alarm time, and importance level. All positional events for a month show up
before the date events for that month (they have a 'date' of zero). Cyclic
events are listed first in the index, before any other types of events.

NOTE: Any event that is scheduled for more than one month is listed in the
index as if it occurred in the _first_ scheduled month. For example, if you pay
the rent on the 15th of every month, the event shows up with the January
events. If you pay your car insurance in March and September, the event shows
up in March.


2.7.2 How Scanning Works

The way Cal's Scan feature works requires some explanation. Cal keeps a 'map'
of all the events listed in the index. This map contains a special flag for
each event. Each flag can be either on or off. When an event's flag is ON, that
event is 'selected' and will show up on the Scan display. When the flag is OFF,
the event will not appear- it will be 'hidden'.

When you first enter the Scan dialog, all the flags are turned ON; that means
all your events can be displayed. To find specific events or groups of events,
you can use the Find dialog. This dialog will look at each event whose flag is
ON, and see if it satisfies your request. If it doesn't, the Find routine will
turn that event's flag OFF.

The Reset button at the bottom of the Scan display will turn all the event
flags ON, no matter what state they're in at the moment.


2.7.3. Scan Display

The title bar in the Scan Dialog displays the number of events currently
selected (those with ON flags) and the total number of events in Cal's
database. The dialog can display up to eight events at a time. The entry for
each event takes up two lines. The first line is in small type, and shows you
the event's index number, what importance level you've assigned the event, the
time of the event's alarm, and when the event occurs. The next line contains,
in large type, the first line of the event's message text. Just to the left of
this text is a small 'bullet'.

If you want to find out more about an event or make changes to it, click the
message text. This takes you to the Edit Dialog, which shows you all the
information about the event. (The Edit Dialog is explained below.)

When you first enter the Scan Dialog, the display is positioned to the first
event in the month you were viewing. Two buttons at the bottom of the dialog,
Prev and Next, allow you to scroll the display forward or back a page at a
time. Several other ways to scroll the display are also available from the
keyboard.

The Clr/Home key will move you to the first event. Shift Clr/Home moves to
the last event. The left and right arrow keys scroll the display one event at a
time, and the up and down arrows scroll a page at a time.

You can use the top row of keys on the main keyboard (numbers 1-0, -, =) to
start the display at the first event in any month, January to December. If
there are no events indexed in that month, the display will show the first
event in the following month. If no events at all occur past that month, the
first event will be displayed.

Note: Remember that cyclic events are indexed before the other types. If you
use the '1' key to move to January, all your cyclic events will have scrolled
off the top of the display... you'll need to scroll back to see them.

You may 'hide' an event by clicking on the bullet next to the event's text.
When you do this, Cal turns the event's flag OFF so it doesn't appear.


2.7.4. Finding Events

The Find button at the bottom of the Scan dialog takes you to the Find Dialog
so you can select a different group of events to display. When you return to
the Scan dialog, only the events that match your selection will be shown. The
next section of this manual explains the Find Dialog.


2.7.5. Scan Options

You have several options available when any events are selected. Click the
title bar of the Scan dialog, and the Scan Options alert will appear. If you
wish, you may erase all the events that you've selected, or you can swap the
'selected' status of all events (those that were hidden will be selected, those
that were selected will be hidden). This gives you an easier way to perform
housekeeping.



2.8. Find Dialog

The Find routine uses the same event-flag method as the Scan dialog. When you
try to find events that satisfy your requirements, Cal checks each event whose
flag is ON to see if it matches. If not, the event's flag is turned OFF. If
there are NO events which satisfy your request, Cal will ding the system bell,
restore the event map to the way it was before you tried your search, and
return you to the Find dialog. Otherwise you'll return from the dialog, and the
event map will have the results of your search.

The Reset button at the bottom of this dialog acts exactly like the one in
the Scan dialog - it turns the flags ON for all your events ("resets the map").
If a search is unsuccessful, you may want to click this button to make sure Cal
looks through all your events.

In some cases, you may enter the Find dialog when ALL the event flags are
turned OFF. When you start a search Cal notices this and gives you the option
of searching through all your events; if you say it's ok, Cal will reset the
event map for you before the search starts.

The Find dialog gives you several ways to specify the events you want to
find. You can search for events that contain a certain string, or use 'filters'
to specify certain event types, status, or importance level.


2.8.2. Search String

The top section of the Find dialog lets you specify a string to search for.
If you enter a string in this field, only events which contain the string will
be selected. You may use the radio buttons below the string to choose if the
search should be case-sensitive or not.

You can search for strings that include non-ASCII characters (those which
don't appear on the keyboard) if you wish. To enter a non-ASCII character in
your string, hold down the ALT key and type in up to three decimal digits on
the numeric keypad. The cursor will turn into a busy bee until you either
release the ALT key or enter three digits. When you do so, the appropriate
character will appear in the string.

Cal can find a string in any part of an event's message text; the string can
appear on any of the three lines. In fact, Cal can even find the string if it
is split between two lines! The end of a line of text is counted as a space
character when searching, so just include a space where the end of a line might
occur. For example, if your event has "This is a sample of an event" as the
first line and "split between two lines" as the second, you could find the
event by using "event split" as your search string.

If you do not enter a string in this field, Cal will find any event matching
the filters you enter below.


2.8.3. Type, Status, Importance Filters

The lower section of the Find Dialog lets you set up 'filters' to give you
more control over the events you find. The first part of this section lets you
find events of a certain type. If you select the button next to one of the four
event types, only events of that type will be included in the search.

If you decide to search for one-time data events, you have the option of
restricting the search to certain years. You should see two entry fields where
you may type in a start and/or end year for the search. If you enter a start
year, only one-time events that occur in that year or after will be found; an
end year restricts the search to events through the end of that year.

The next part allows you to restrict your search to only expired events or
events that have valid HotWire alarm information; again, select the button next
to the type of event you want to find.

The bottom part of the dialog lets you specify importance levels you're
interested in. There are eleven buttons across the dialog, marked 0-9 and one
button that is blank. If you select any of these buttons, only events whose
importance matches a selected button will be found. The empty button will
deselect all the importance buttons, so that events of any importance will be
allowed.

Once you've set up the dialog to find a group of events, click the Select
button or press Enter. Cal will find all the events that match your parameters
and return you to the previous dialog. If no events match, Cal will ding the
system bell and you'll return to the Find dialog.



2.9. Edit Dialog

The Edit Dialog allows you to add, change, or erase events stored in Cal's
database. You can reach this dialog two ways: either click on a message slot in
the Alert Dialog, or click on a message slot in the Scan dialog. If you enter
the Edit dialog by clicking on a message, the edit screen will display all the
information on that event; if you click on a blank slot instead, Cal will show
you the first event on that day. If no events are scheduled on a day, the Edit
dialog will show you an empty 'template' ready for you to add a new event.

This is the most complicated dialog in the Cal system, so it deserves careful
study. We'll start with a discussion of a few basic concepts.


2.9.1. Edit Mode

Cal supports four different types of events. Each type is scheduled in a
different manner, so Cal needs to provide a way to enter the data for any event
type. Cal does so by providing three different 'edit modes' - Date mode (for
recurring and one-time date events), Position mode, and Cyclic mode. Most of
the fields on the Edit screen are the same for each mode, but the section
regarding when an event occurs is different for each.

The screen for editing Date events contains a number of month buttons, plus
fields where you can enter a date and year to specify when the event occurs.
The Position mode screen contains the same month buttons, but instead of fields
for a date and year, you will see radio buttons where you can select a week and
weekday for an event. The screen for Cyclic events has fields for you to type
in the date of the event's first and last occurrence, and the number of days
between each occurence of the event.


2.9.2. Fields on the Edit Screen

First, take a moment to look at the dialog. Most of the dialog is taken up by
a large box. The top section of this box shows you the message text for each
event. Up to three lines of text are allowed here. The first line has a box
around it to remind you that only the first line of text is displayed in the
Scan dialog.

The center of the edit screen shows you all the information needed for
scheduling the event. This portion of the screen will be different for each
different mode; in Date mode you'll see the date entry fields, in Position mode
you see the week and weekday buttons, and in Cyclic mode you see the start/end
dates and the period.

The lower part of the large box contains information common to all event
types: fields for the importance level, the number of days advance notice for
the event, and for HotWire alarm events, the time of day and slot number for
the alarm.

Directly under the large box are two long, skinny buttons. The first button
lets you switch from one edit mode to another; click this button (or press the
Alt and 'M' keys) to toggle between date mode, position mode, and cyclic mode.
The second button lets you jump to the next event on a particular day; click
the button, or press Alt-N.

Across the bottom of the Edit dialog you'll see a number of action buttons.
These buttons allow you to find an event with the Find dialog, erase an event,
replace an existing event, or add a new event. The last button lets you exit
the Edit dialog.


2.9.3. Looking at Events

Now let's see how to look at an event. If you clicked on the text of an event
message to get here, then the Edit dialog will show you all the information on
that event. If you clicked on a blank message slot, then all the fields here
will be blank or in their default states.

For the moment let's assume there's an event showing. The message field at
the top tells you which event you're looking at. You can see the event's
importance, days advance notice, and alarm information at the bottom of the
screen. These fields should be pretty easy to understand.

The center part tells you exactly when the event is scheduled: if the event
occurs in a particular month, then that month button will be selected. If an
event occurs in more than one month, all the appropriate month buttons are
selected. If this is a cyclic event, the start/end dates are shown.

When you look at a date event, the date on which the event falls is listed on
the right. If this happens to be a one-time event, the year in which the event
occurs is shown on the left.

IMPORTANT NOTE: THIS IS THE ONLY DIFFERENCE BETWEEN A NORMAL DATE EVENT AND A
ONE-TIME DATE EVENT. If there's a year in the box, it's a one-time event;
otherwise it's a normal recurring date event. One-time events expire; recurring
events don't.


Now that that's straight, let's see how to look at a _different_ event.


If more than one event is scheduled on the day (or position in the month)
you're looking at, simply click the skinny Next Event button (or press Alt-N).
Every time you click this button, Cal shows you the next event on this
schedule. Click the button as often as you wish to cycle through all the events
on that day. After the last event on this schedule is displayed, you'll see an
empty template; click the button again to start back at the first event.

If only a single event, or no events at all, are scheduled on that day, then
you need to change days. To do so, just change any of the month or position
buttons, or type in a different date, then click the Next Event button.
Whenever you click this button, Cal looks to see what schedule you've selected,
then goes through his database looking for events on that schedule. If any are
found, Cal will display them one at a time.

IMPORTANT NOTE: If you wish, you can select more than one month button for
your search. When you do this, you'll be able to scan through all the events
matching your schedule that occur in any of the months you select. For each
event, Cal will use the month buttons to show you when the event is scheduled,
but will still remember which month buttons YOU selected. If _YOU_ change the
month buttons, then Cal will use your choices for looking at events. If _CAL_
changes the month buttons to show when an event occurs, that WON'T change the
months you selected. Cal will continue to use your month selections until you
change the edit mode, or select different month buttons on the dialog. (Note:
Cal won't store your selections until you actually change the month buttons
yourself.)


Let's say you're looking at date events, but you want to switch over and look
at a positional event. It's easy to do - just click the skinny button marked
'To Position Mode' near the bottom left. Cal will shift to Position Mode; then
you select the buttons for whatever schedule you want. When you've done that,
click the skinny Next Event button. That makes Cal look for events on your
selected schedule.

When you get into position mode, look at the skinny mode button you just
clicked: it now reads 'To Cyclic Mode'. Also, the skinny Next Event button
reads 'Next Pos Event'. Whenever you click the Mode button, Cal toggles between
Date mode, Position mode, and Cyclic mode. The skinny buttons change their
markings to show you what effect they'll have.

NOTE: Whenever you change edit modes, Cal looks through the event map and
turns OFF the flags for any events that aren't of the new type. This won't
cause a problem, but it may confuse you if you're not expecting it!


If you want to find a particular event, you can use the Find dialog to help;
just click the Find button at the bottom of the screen. Use the dialog, and
when you exit, the next event you found will be displayed.

NOTE: 'Next event' means the first marked event whose position in the index
follows the event that was on the screen when you called Find. On occasion
there WON'T BE ANY MARKED EVENTS that are indexed AFTER the previous event.
When this happens, you'll see an empty template on the screen. To view your
events, just click the Next Event button and you'll see the first marked
event.


2.9.4. The When Dialog

Any time the Edit dialog is showing a valid cyclic event, the small "Show
When" button in the middle of the screen will be enabled. If you click this
button, you will see the When Dialog for that event. This dialog lists the date
of every occurrence of the event. Use the 'Past' and 'Future' buttons to scroll
forward and back through the list. If you wish, you can click on one of the
dates- when you do so, you return to the main calendar screen, showing the
calendar for the date.


2.9.5. Changing Existing Events

Now that you've seen how to _look_ at an event, you can learn how to _change_
an event. You'll be pleased to know that it's simple... just find the event,
then change its message, schedule, importance, days notice, or whatever. When
you've finished the changes, click the Replace button at the bottom of the
screen. When you do this, Cal erases the old event you were looking at, then
adds whatever you typed in as a new event. Any settings you didn't change are
left as they were.

Cal has several features to make editing events simpler. When you're editing
a text field, you can use the shifted left and right arrow keys to move to the
beginning or end of the field you're editing. The Clr/home key will move the
cursor right to the first line of the message; shifted, to the HotWire alarm
slot. (The up and down arrow keys also 'wrap around' these two fields.) You can
even enter non-ASCII characters in a field by holding down the Alt key and
typing in three decimal digits on the numeric keypad.


2.9.6. Adding New Events

Adding a new event is as simple as changing an existing one- in fact, the
process is exactly the same. The only difference is that to add a completely
new event, you should click Add instead of Replace.

When an empty 'template' appears on the screen, just enter the information
you need to define a new event. Or go ahead and type over an event that's
already displayed on the screen- when you click Add, the old event isn't
changed at all; a brand new event is added to the database. However, if the
event you type in exactly matches an event already in the database, you'll be
told that the event exists and the duplicate will not be added.

NOTE: When adding a Cyclic event, you're asked to enter dates using numbers
for the year, month, and day. By default, Cal is set up to use USA style dates
- this means you need to enter the month, then the day, then the year. However,
if you have selected the 'Euro Dates' option in Preferences, Cal will expect
you to enter the day first, then the month and year. Remember to enter the
month and day in the correct order!

ANOTHER NOTE: There's one editing shortcut that may come in handy. If you are
editing a date event, you can type a year into the Year field to create a
one-time date event.  Since you'll usually want to insert the current year, you
can simply click the word "Year:" on the Date edit screen (or press Alt-Y);
doing so will insert the current year in this field, and move the cursor to the
field as well.


2.9.7. Erasing Events

An event can be erased by clicking the button marked Erase on the bottom of
the screen. Simple enough, eh?

WARNING: BEFORE you click the Erase button, be SURE you're pointing to the
right event! Cal remembers the last event displayed on the screen. If you
change the month buttons or other scheduling fields, be sure to click the Next
Event button _before_ you click Erase - this will guarantee that Cal is
pointing to the right event. If you're not careful, you'll erase something you
don't want to lose!


====================================================


3. Calshow

Calshow was designed primarily as an AUTO program to remind you of upcoming
events whenever you boot your Atari. You can also run Calshow as a normal GEM
program or desk accessory to see a list of upcoming events at any time, or to
write several types of reports to a printer or disk file. This version of
Calshow has been completely rewritten to be more efficient, and all its
functions are now available from a single dialog.

Basically, Calshow finds your copy of Cal, reads its event database, and
displays on screen any events that will occur within a short period of time.
The display can include the number of days until the event, the date on which
the event falls, the alarm time, and the message you entered for the event.



3.1. Running from the AUTO Folder

The easiest way to run Calshow is directly from your AUTO folder. When you do
so, it provides you with a list of upcoming events whenever you boot your
Atari.

When you run Calshow, the first thing it does is look for your copy of Cal.
There's a way to tell Calshow exactly where you keep Cal- that's explained in
the section below on running as a program. But even if you haven't told Calshow
where to find Cal, chances are Calshow can find it!

Calshow first looks for Cal wherever you told it to look. If it can't find
the file, or if the file turns out not to be Cal, Calshow looks at all the
other files in that folder whose names match the pattern "CAL*.AC?". If none of
those are Cal, Calshow checks all "CAL*.PR?" files.

If none of the files checked turn out to be Cal, Calshow takes more drastic
measures. It checks _seven more folders_ looking for any file with the name you
specified, or whose name matches one of the patterns above. First, Calshow
looks in the folder from which it was run. Then it looks in the root directory
of the same disk. If that doesn't work, Calshow keeps on looking in these
folders: \ACCS\, \MULTDESK.MDX\, \MULT_MDX\, \DESK\, \DESKACCS\, and \ACC\. If
Calshow still can't find Cal, it gives up (and shame on you for hiding it! :-).

NOTE: If one of the files Calshow examines _is_ Cal but doesn't have any
events in its database, Calshow ignores it and continues looking.


After Calshow finds Cal, it reads in the event database and displays a list
of upcoming events. Calshow displays an entry for every event whose advance
notice period is close enough to today's date. (Normally Calshow will display
up to one screen's worth of upcoming events, but you can change this setting;
see the section below on running Calshow as a program.) The entry includes the
number of days before the event, the date on which the event falls, and the
message you defined for the event.

As distributed, Calshow will display any event, no matter what its importance
level. This setting can be changed as well; again, see below for more
information.


Once Calshow has displayed the list of upcoming events, it pauses for a
moment so you can read the list. The normal wait period is 15 seconds (but this
setting too can be changed to suit you). After this amount of time has passed,
Calshow finishes running and your bootup process continues. You can press any
key to make Calshow quit before time has expired, or press the HELP key to make
Calshow wait for a keypress before continuing.

NOTE: If Calshow can't find a valid copy of Cal, or there are no events
happening soon enough to display, Calshow will display a message on the screen
and pause for _one second only_. This means your bootup won't be delayed
unless there's a good reason.

Versions 6.1 and later have a feature that lets you tell Calshow to display
events only on the first boot of each day (see Preferences below). If you
reboot your ST and wish to see the display anyway, hold down the Alternate key
as Calshow loads. If you want to skip Calshow's display for some reason, hold
down the Control key instead.


IMPORTANT NOTE: Calshow uses your GEMDOS clock to determine the current
date. If you have an external clock chip but you can't get Calshow to display
the correct date when you run it from the AUTO folder, it may be that your
clock program is only setting the keyboard clock. You can correct this by
running a program such as CLOCKSET.PRG (freeware from Little Green Footballs
and Charles F. Johnson) before Calshow runs. This program reads the keyboard
clock and sets the GEMDOS clock, so the date will be correct.



3.2. Running as a PRG or ACC

Calshow provides you with MUCH more control over its output when you run it
as a program or desk accessory. In addition, you can configure a number of
settings, such as those mentioned above, to tailor Calshow's behaviour. You can
save these settings in the Calshow file so they will be active the next time
you run Calshow at boot time.


3.2.1. Calshow Prefs

The top section of the Calshow dialog allows you to set up your options.
First you see a box labelled "Show __ Events": this box lets you set the
MAXIMUM number of events Calshow will display. You can type in a specific
number of lines, or leave the value as zero. If you say zero, Calshow will try
to determine the size of your Atari's screen and display only the number of
events that will fit.

IMPORTANT NOTE: Calshow may not display this number of events every time...
it depends on the days notice you defined for each event! Remember, this is the
MAXIMUM!

Next is a field that says "Pause ___ Seconds". This field controls the length
of the pause after Calshow has displayed its event list. Type in any number
from zero to 999 seconds here.

IMPORTANT NOTE: IF YOU SET THIS FIELD TO ZERO, CALSHOW WILL WAIT FOREVER FOR
YOU TO PRESS A KEY! Keep this in mind when you're deciding on a value to enter
here.

Beneath these two fields are a pair of buttons marked Once and Euro. If you
select the Once button, then Calshow will only display upcoming events on the
first bootup of each day; if you reboot later in the day, you must hold down
the Alternate key when Calshow loads if you wish to view the display.

NOTE: Calshow uses the date stamp on the Calshow program file to determine
if each bootup is the first for the day. You must not write-protect Calshow if
you want to take advantage of this feature.

The Euro button tells Calshow to expect European-style dates (day, month,
year) instead of USA-style dates (month, day, year) for the start and end
dates entered below.

The next button is marked "Locate Cal". This is the way to tell Calshow
exactly where your copy of Cal is located. Click on the button and use the item
selector to find your Cal program file.

IMPORTANT NOTE: Cal doesn't actually have to be in the folder you locate!
Calshow will store the path and filename you select, even if the file isn't Cal
or doesn't even exist. This means you can configure Calshow first, then move a
copy of Cal into the right place later. You'll see an alert that warns you of
any error, but the information will be stored in memory anyway.

The next button in this part of the dialog is marked Save Setup. Click this
button, then use the item selector to locate Calshow; all the settings in the
top section of the dialog will be saved in the program file, and will be in
effect the next time you run Calshow.

Beneath these two buttons is a group of ten buttons marked 0-9. These buttons
tell Calshow which importance levels to show. If the button corresponding to an
event's importance level is NOT selected, that event WON'T be shown in
Calshow's display.


3.2.2. This Run Only

The lower section of the Calshow dialog lets you decide what sort of display
you want. You'll see two groups of radio buttons, and a space to enter two
dates. None of the information on this half of the dialog is saved; it only
pertains to this particular run.

The first group of buttons allows you to choose one of three styles of
output. Select the button for the type of output you desire. The first type,
Coming Events, produces a report on events that will occur in the near future.
Each line of this report will contain the number of days before the event (in
bold print), the date and time of the event, and the message (underlined). If
the event has more than one line of text, each line will be displayed.

The second type, Datebook, will produce a datebook-like list with one entry
for every day in the time period you specify. The starting month and year are
listed on one line. Under this, another line lists the date and day of the
week. Then, if there are any events scheduled for that day, the event messages
are listed on a separate line, preceded by the event's alarm time. This type of
list is most useful when you specify a time period of a week or month; you may
want to use the Datebook output as a to-do list.

The last option allows you to produce a Master List of all the events you've
stored in Cal's database. If you choose this type of output, any starting or
ending date you've entered is ignored; every event in Cal is listed, one event
per line (with extra lines if the event uses more than one line for its
message). Each entry contains the event number, letters to indicate the months
in which the event occurs, the date or position on which the event falls, the
alarm time and number of days advance notice you've set, the event's
importance, and the event message. For a cyclic event, the entry shows the
number of days between occurrences and the date of the first occurrence. You
have the option of listing all events or only those matching the importance
levels you've selected.

The second group of radio buttons lets you choose where to send Calshow's
output. The three buttons are marked Video, Printer, and File. Simply select
the button corresponding to the type of output you want - on screen, printed
hardcopy, or a disk file.

NOTE: The video display on screen only supports the Coming Events listing.
That shouldn't be a problem, since the other report styles are of limited
usefulness on screen. When you direct output to a printer or disk file, you may
choose any of the three reports.


Underneath these setup items are boxes where you can enter a specific start
or end date for Calshow's display. These dates are only valid when running
Calshow as a program or accessory; at boot time, Calshow will always show you
a display of upcoming events according to the date set in your ST's clock.

NOTE: If your ST doesn't have a built-in clock, then you probably have an
AUTO program to set the time from a separate clock chip, your hard disk, or
some other method. Be sure this program runs BEFORE Calshow when you boot, or
the events you see won't be the ones you want to see!

When you enter a new starting date, Calshow pretends that that date is the
current date. You don't need to enter a complete date here; if you just want to
see a list of events for the first part of May, simply enter the number "5" in
the month field. When you enter a year, any two-digit number is assumed to be
in the 1900s and any one-digit number is treated as if it's in the 2000s. Thus,
a year of "93" would be 1993 and a year of "1" would mean 2001.

You can enter a new ending date in the same fashion. Of course, Calshow will
warn you if you try ending the display before it starts.

IMPORTANT NOTE: If you enter an ending date, CALSHOW WILL IGNORE THE DAYS
ADVANCE NOTICE SPECIFIED FOR EACH EVENT. When you tell Calshow the end date you
want, it assumes that you want a complete list of events up to that date
regardless of the advance notice. Calshow will keep showing events until this
end date is reached OR the maximum number of events has been shown. (Remember,
you set up the maximum in the "at most" field above.)



Four buttons appear at the bottom of Calshow's dialog. The one on the left,
Exit, allows you to exit Calshow. The one on the right is marked "Go!". When
you click this button or hit Return, Calshow will format the report you
selected. If you asked for output to a printer or disk file, Calshow closes its
window while the list is being prepared. When the operation has completed,
you'll return to the desktop.


Calshow 6.2 adds two new 'quick-view' buttons, "Week" and "Today". These
buttons let you instantly select a video display of coming events for the day
or for the next week. Unlike the standard Calshow display, the advance notice
for your events is ignored so you get a full picture of upcoming events.


When you've chosen Video output, you'll see a GEM window appear. The
information line under the title bar tells you the starting date for Calshow's
list of events. The rest of the window displays upcoming events according to
the options you specified above. First the number of days before the event is
shown in bold letters, then the day of the week and the date appear in italics.
The alarm time for an event will appear in normal type, or a dashed line if the
event has no alarm. The rest of the line is underlined, and contains the
message for the event.

At the bottom of the screen, you'll see one of two messages. If the entire
list of events fits on a single screen, Calshow will display the message "press
any key to continue". You can press a key to exit Calshow, or simply wait for
the pause time you entered above to expire. When this happens, you'll return to
the desktop.

If there are more events to display than will fit on a single screen, Calshow
displays the message "press a key to go on or UNDO to quit". If you press the
UNDO key, Calshow will exit to the desktop. If you press any other key, or wait
for the pause time to run out, Calshow will clear the screen and display a
second group of events. This process continues until all events waiting to be
shown have been displayed.

You can press the HELP key at any time. When you do so, Calshow will wait for
you to press any key (including Help) before it continues.


Once Calshow has completed a display, you return to the Calshow dialog. You
can choose to see another Calshow display, or you can exit the program by
clicking the eXit button or pressing UNDO.


====================================================


4. Final Notes, Version History


Cal and Calshow were written completely in assembly language using the HiSoft
DevpacST assembler. The resources were created with WERCS and converted to
assembly code using a program written by Carl Barron. Thanks to Robert
Birmingham for convincing me to add events to my simple calendar program, and
to Myles Cohen, Colin Robertson, and many others for some great suggestions!
Many thanks also to the CodeHeads for telling me how to hook into HotWire and
to the Double Click folks for help getting these programs working with
DC-Squish. Special thanks are due Charles F. Johnson for hints on letting a
program figure out if it's an ACC or AUTO program.

And, of course, many thanks and best wishes to the folks who've sent cards
and letters (and donations) -- people like you keep shareware authors writing!

The calendar routine I use in Cal was based on Zeller's Congruence, which
explains a simple way to calculate the day of the week for a given date without
resorting to a lookup table. Articles dealing with this subject appeared in
Computer Language Magazine, March and December 1988. (The articles were
helpful, although they included a couple of typographical errors. :-) Also note
that the modern Gregorian calendar wasn't invented until the 1580s, something
to keep in mind if you're poking around in the dim and distant past <grin>.

Please let me know if you use this program!!! Comments, suggestions,
requests, and bug reports are all welcome. Remember: if you find a bug but you
don't let me know about it, chances are I won't fix it. :-)

This program is distributed as shareware - try Cal out for awhile, and if you
decide to keep it, send a donation to me at the address below. For every
donation of $25 or more, I'll send a disk containing the latest versions of all
my programs (Cal, the Whatis File Identifier, KXPset Printer Setup Utility).
But even if you don't want to contribute right now, please send a postcard!


      Bill Aycock
      2310 North Elm Street
      Greensboro, NC 27408-5120

      Compuserve ID: 76703,4061
      Internet: [e-mail]
      February 15, 1992

PS- The latest version of Cal is always available in Compuserve's Atari
    Productivity Forum (GO ATARIPRO at any ! prompt). Since I'm on the
    Forum's staff, I always upload there first. For fastest response to
    inquiries, post a message to me in ATARIPRO.

PPS- If you somehow lose my address, just press the Help key from Cal's main
     screen. :-)

================
Version History:
================

v6.2: Cal: more displays of alarm time; more Scan options; When dialog to show
      cyclic event dates; more date calculations; ability to move dialog on
      screen; Calshow: alarm time displayed, events sorted by alarm time; new
      Week and Today buttons; return to menu instead of exit
v6.11 both: corrected keyboard shortcuts and mouse handling in ACC mode
v6.1: Cal: adds ability to communicate with other Cal ACCs; Calshow: allows
      European date format, once-per-day bootup display
v6.02 Cal: fixed 'invisible' level-0 events, edit logic change; Calshow: fixed
      max display lines, problem when cancelling a locate-Cal process
v6.01 allowed shifted command keys; in Cal: corrected Cancel key in Mass
      Erase, added default importance level, honors alarms-disable button,
      extended cyclic period to up to 255 days; fixed Calshow to save
      importance filter, allowed Master List to pay attention to importance
      filters
v6.0: complete rewrite: added cyclic events, file load/save, importance
      levels, keyboard shortcuts, many many more changes!
v5.3: fixed Cal & Calshow to work if system date is not valid
v5.2: added extended data area; fixed Calshow to recognize any 5.x version
v5.1: Cal: added alert when no room remains to add an event
v5.0: Cal: added compatibility with DC-Squish; three importance levels; one
      event can occur in multiple months; specify advance notice separately
      for each event; Hotwire alarm feature; bug fixes, optimizations, etc.
      Calshow: completely rewritten to run as a GEM program or ACC or from
      AUTO folder; DC-Squish compatible; new Datebook and Dump output
      options; importance filter for event displays; lots more stuff
v4.7: added support for significant/non-significant events
v4.5: added multiple positional events; when saving setup, file selector now
      defaults to path Cal loaded from; allow more events on single day; added
      code to help guard against unusual March start date problem
v4.4: added option to supress add/replace/erase event alerts; added case
      sensitive search; retains search string between searches
v4.3: fixed a logic bug occurring when exiting Cal in some circumstances;
      added keyboard exit from Browse screen
v4.2: added Replace button in Edit; added option to ignore expired events;
      added type filters to Find function; changed Browse logic
v4.1: added grow/shrink box support; added leap-year check for one-time
      events on Feb 29; skip saving duplicate events; sundry other tweaks
v4.0: added multiple events on the same date; added alphabetic sort; added
      one-time events and expired-event handling; various other tweaks
v3.5: fixed filepath setup for standard GEM file selector problem
v3.4: fixed logic error in Calshow; enabled 'last' week position button
v3.3: fixed obscure bug in Find function; redesigned Browse screen and Today
      button logic; added Prev and Next month buttons; added option to save
      changed setup when exiting
v3.2: fixed occasional bus errors after erasing events and then browsing;
      included Calshow for bootup reminders
v3.1: first released version supporting events
v2.0: final calendar-only version

====================================================

5. Keyboard Shortcuts

5.1. Main Calendar

      UNDO                 Exit
      HELP, Space bar      credits, statistics
      numbers 1-0, -, =    month buttons
      keypad 1-9, (, ), /  month buttons
      Clr/Home             January
      shift Clr/Home       December
      R arrow              next month
      L arrow              previous month
      Up arrow             forward one year
      shift Up arrow       forward ten years
      Down arrow           back one year
      shift Down arrow     back ten years
      Y                    Year dialog
      F1, /, ?             extras dialog
      F2, T                Today
      F3, P                Preferences dialog
      F4, F                File dialog
      F5, S                Scan dialog


5.2. Alert Dialog

      UNDO                 Exit
      numbers 1-8          select event 1-8
      keypad 1-8           select event 1-8
      F1, N, space bar     Next page


5.3. Edit Dialog

      UNDO                 Exit
      Alt-M                toggle Mode
      Alt-N                Next event
      Alt-W                When dialog (cyclic events)
      Alt-Y                this Year (date events)
      F1, Alt-F            Find dialog
      F2, Alt-E            Erase event
      F3, Alt-R            Replace event
      F4, Alt-A            Add event


5.4. Expired Event Dialog

      UNDO                 Exit
      F1, C                Convert event
      F2, E                Erase event
      F3, I, space bar     Ignore event


5.5. Extras Dialog

      UNDO                 Exit
      F1, C                Calculate
      D, ^ R arrow         Day/month/year order
      M, ^ L arrow         Month/day/year order


5.6. File Dialog

      UNDO                 Exit
      F1, Alt-L            Load from file
      F2, Alt-S            Save to file
      F3, ^ R              Rescan for acc
      F4, ^ L              Load from acc
      F5, ^ S              Save to acc
      F6, Alt-M            Merge from file
      F7, Alt-E            mass Erase dialog
      F8, Alt-A            set Alarms
      F9, Alt-X            check eXpired events


5.7. Find Dialog

      UNDO                 Exit
      ^ L arrow            case sensitive
      ^ R arrow            not case sensitive
      Alt-A                Alarm events
      Alt-C                Cyclic events
      Alt-D                Date events
      Alt-E                Expired events
      Alt-O                One-time events
      Alt-P                Positional events
      ^ space bar          clear importance flags
      F1                   reset event flags
      F2                   select events


5.8. Mass Erase Dialog

      UNDO                 Exit
      numbers 1-0, -, =    month buttons
      keypad 1-9, (, ), /  month buttons
      A                    erase All events
      F1, E                Erase events


5.9. Preferences Dialog

      UNDO                 Exit
      F1                   accept changes


5.10. Scan Dialog

      UNDO                 Exit
      HELP                 scan options alert
      numbers 1-0, -, =    first event in that month
      keypad 1-8           select event 1-8
      ^ 1-8                hide event 1-8
      Clr/Home             first event
      shift Clr/Home       last event
      L arrow              back one event
      R arrow              forward one event
      Up arrow             back one page
      Down arrow           forward one page
      F1, R                Reset event flags
      F2, F                Find dialog
      F3, P                Previous page
      F4, N                Next page


5.11. When Dialog

      UNDO                          Exit
      P, L arrow, U arrow, F1       Past
      F, R arrow, D arrow, F2       Future
      1-0                           go to date 1-10


5.12. Calshow Dialog

      UNDO                 Exit
      HELP                 wait for keypress
      C                    Coming events report
      E                    European date format
      F                    File output
      G                    Go!
      L                    Locate Cal
      D                    Datebook report
      M                    Master list report
      O                    Once per day boot display
      P                    Printed output
      S                    Save setup
      T                    Today quick-view
      V                    Video (screen) output
      W                    Week quick-view


Cal 6.2a update:

In version 6.2, if Cal was running as a resident accessory, and the user
selected the Location button in Prefs to use the saved location, and the
user moved Cal from its centered position, then the window behind Cal
would appear at progressively larger offsets each time the accessory was
opened. This update corrects the problem.

Calshow 6.2a update:

This update adds one feature. Once you have selected a group of
importance filter buttons, you may click the small "Importance Filters"
text to toggle the state of the buttons. If you double-click the text, all
importance levels will be selected. This feature should make it easier to
select a desired group of importance filters.


Bill Aycock
19 February, 1992